GeneDock workflow client手册

(一) 简介

GeneDock workflow client (gwc) 是基于GeneDock Official Python SDK (gdpy) 开发的命令行客户端，用户通过简单的命令行操作便可与GeneDock平台进行交互，用于管理和操作工具、工作流与任务等资源。与直接调用API或SDK相比，gwc使用起来更方便、更快捷，更有利于用户进行自动化和批量化操作。

(二) 安装

(1) 环境依赖

此版本的gwc (GeneDock workflow client) 适用于Python 2.6、2.7、3.3、3.4、3.5版本。

首先请根据python官网的引导安装合适的Python版本。
安装好Python后：
- 在Linux Shell里验证Python版本：
```
   $ python -V
   Python 2.7.10
```
  上面的输出表明您已经成功安装了Python 2.7.10版本。
  
  提示：：
  macOS系统与Linux系统操作类似，下文不再赘述。
- Windows CMD环境下验证Python版本：
```
   C:\> python -V
   Python 2.7.10
```
  上面的输出表明您已经成功安装了Python 2.7.10版本。如果提示“不是内部或外部命令”，请检查配置“环境变量”-“Path”，增加Python的安装路径。
确认是否安装python包管理工具——pip。
- 在Linux Shell里验证是否安装pip：
```
  $ pip -V
  pip 9.0.1 from /usr/local/lib/python2.7/site-packages (python 2.7)
```
  上面的输出表明您在python2.7默认的模块安装路径下已经成功安装了pip。
- Windows CMD环境下验证是否安装pip：
```
   C:\> pip -V
   pip 9.0.1 from C:\Python27\lib\site-packages (python 2.7)
```
  上面的输出表明您在python2.7默认的模块安装目录下已经成功安装了pip。如果提示“不是内部或外部命令”，请检查配置“环境变量”-“Path”，增加pip的安装路径。
- 如果没有安装，以Linux为例，可采用以下两种方法:
  
  1) 使用脚本安装：
  
  根据pip官网的引导，下载“get-pip.py”脚本进行安装（需默认安装setuptools）。
  
  2) 使用软件管理器安装：
  
  Debian 和 Ubuntu:
```
  sudo apt-get install python-pip
```
  Fedora:
```
  sudo yum install python-pip
```
  提示：
  
  通过此方法安装的一般不会是最新版本的pip。

(2) 安装gwc (GeneDock workflow client)

pip在线安装

从 pypi安装：
```
 pip install gwc
```
pip本地安装

从 Genedock的pypi源下载工作流客户端安装包*.whl

例如：

```
pip install gwc-0.4.1-py2.py3-none-any.whl 
```

验证

在命令行输入gwc -v并回车:
```
 $ gwc -v
 gwc 0.1.0
```
上面的输出表明您已经成功安装了gwc，版本为0.1.0。

(3) 卸载gwc (GeneDock workflow client)

建议通过pip卸载：

pip uninstall gwc

提示：

如果卸载过程中提示“Permission denied”，请切换到root用户或利用sudo权限 (“sudo pip uninstall gwc”)。

(三) 快速入门

在确认您已熟悉GeneDock平台关于工具、工作流和任务等的基本概念和操作之后，通过本节您将看到如何通过gwc (GeneDock workflow client) 以命令行形式对其基本功能进行操作。

(1) 配置

配置账号相关信息

交互式:
```
 gwc config
```
命令行:
```
 gwc config -e ENDPOINT -i ACCESS_KEY_ID -k ACCESS_KEY_SECRET 
```
参数说明：

-e【ENDPOINT】：（必填）例如：cn-beijing-api.genedock.com（北京域）。默认使用https协议，仅部分私有云使用http协议，需指定url为http://, 如 http://cn-beijing-api.genedock.com。

-i【ACCESS_KEY_ID】：（必填）如何获取密钥请参考命令行客户端使用手册中获取access_key_id和access_key_secret的说明。

-k【ACCESS_KEY_SECRET】：（必填）如何获取密钥请参考命令行客户端使用手册中获取access_key_id和access_key_secret的说明。

-a【ACCOUNT_NAME】：（必填）申请的组织账号名

-u【USER_NAME】：（默认：admin）用户名

提示：

配置完成后，下次使用时无需重新配置。若需要修改配置信息，需重新配置一遍。
列出当前配置信息
```
 gwc config ls
```

(2) 工作流相关操作

列出工作流

列出所有有权限的工作流（包括自己创建的工作流、安装的公共工作流和被授权的工作流）：
```
 gwc workflow ls
```
列出指定账号下的工作流：
```
 gwc workflow ls -a ACCOUNT
```
参数说明：

-a【ACCOUNT】: （选填）工作流所属的资源账号，例如列出安装的公共工作流时，ACCOUNT为public
下载工作流参数配置模板
```
gwc workflow getparam [-h] -n NAME [-o OUTPUT] [-v VERSION] [-a ACCOUNT]
```
参数说明：

-n【NAME】：（必填）工作流名称

-o【OUTPUT】：（选填）指定输出文件的路径，不填则输出到屏幕。wdl工作流输出的是JSON格式文本

-v【VERSION】：（选填）工作流版本，不填默认以最新版本运行

-a【ACCOUNT】：（选填）工作流账号归属，不填默认此工作流属于当前账号
运行工作流
```
 gwc workflow run [-h] -n NAME -p PARAMETERS [-v VERSION] [-a ACCOUNT] [-t TASK] [-d REMOTE_OUTPUT_DIR]
```
参数说明：

-n【NAME】：（必填）工作流名称

-p【PARAMETERS】：（必填）工作流运行时所需的配置文件，可通过“下载工作流参数配置模板”（gwc workflow getparam）获得

-v【VERSION】：（选填）工作流版本，不填默认以最新版本运行

-a【ACCOUNT】：（选填）工作流账号归属，不填默认此工作流属于当前账号

-t【TASK】：（选填）运行工作流指定task名称，不填则为系统默认生成名称

-d 【REMOTE_OUTPUT_DIR】：（选填）当前只支持wdl工作流，不填写则为默认的输出目录

提示：

通过getparam下载工作流参数配置模板后，必须填充输入项的数据路径（配置文件Inputs:\<loadata>:data:name处）方可运行工作流。输出项的数据路径可选填，不填则为系统默认生成的路径和名称。

设置工作流参数配置模板
```
 gwc workflow setparam -n NAME -c CONFIGS [-v VERSION]
```
参数说明：

-n【NAME】：（必填）工作流名称

-c【CONFIGS】：（必填）工作流参数配置文件（yaml格式），通过“下载工作流参数配置模板”（getparam）获取并进行修改

-v【VERSION】：（选填）工作流版本，不填默认以最新版本运行

提示：

通过getparam下载工作流参数配置模板后，可以修改输入项和输出项的数据路径，以及参数项，与网页版“工作流–预设运行配置”功能一致。wdl工作流暂不支持该功能。

创建工作流
```
gwc workflow create -n NAME -c CONFIGS [-v VERSION] [-t TYPE][-p IMPORTS]
```
参数说明：

-n【NAME】：（必填）工作流名称

-c【CONFIGS】：（必填）工作流配置文件,wdl工作流用wdl格式，gwl工作流采用yaml格式

-v【VERSION】：（选填）工作流版本，不填默认为1，后面版本自动加1
-p 【IMPORTS】:(选填)只适用于 wdl类型的工作流。创建wdl工作流依赖的zip文件
下载工作流配置文件
```
 gwc workflow get -n NAME [-v VERSION] [-o OUTPUT]
```
参数说明：

-n【NAME】：（必填）工作流名称

-v【VERSION】：（选填）工作流版本，不填默认为最新版本

-o【OUTPUT】：（选填）指定输出文件夹，不填则输出到当前目录下的 <工作流名称>_<工作流版本>

提示：

可对下载的工作流配置文件进行修改，修改后的配置文件用于更新工作流配置文件或创建工作流（含新版本）。wdl工作流会下载wdl原始文件及其对应的依赖文件。

只支持下载该账号下的工作流模板
更新工作流配置文件
```
 gwc workflow update -n NAME -c CONFIGS [-v VERSION] [-p IMPORTS] [-r]
```
参数说明：

-n【NAME】：（必填）工作流名称

-c【CONFIGS】：（必填）工作流配置文件，通过”下载工作流配置文件“（gwc workflow get）获取并进行修改

-v【VERSION】：（选填）工作流版本，不填则增加高版本的工作流

-p 【IMPORTS】：（选填）只适用于wdl。更新wdl工作流所需的依赖zip包

-r ：（选填）只适用于wdl。更新工作流的时候，是否需要去除原来的工作流依赖zip包，否则保留原来的依赖包

删除工作流
```
 gwc workflow delete -n NAME [-v VERSION]
```
参数说明：

-n【NAME】：（必填）工作流名称

-v【VERSION】：（选填）工作流版本，不填默认为最新版本

(3) 工具相关操作

备注：不适用于wdl工作流

列出工具

列出所有有权限的工具：
```
 gwc tool ls
```
列出指定账号下的工具：
```
 gwc tool ls -a ACCOUNT
```
参数说明：

-a【ACCOUNT】: （选填）工具所属的资源账号，例如列出公共工具时，ACCOUNT为public
创建工具
```
 gwc tool create -n NAME -c CONFIGS [-v VERSION]
```
参数说明：

-n【NAME】：（必填）工具名称

-c【CONFIGS】：（必填）工具配置文件（yaml格式），可参考genedock-workflow-client/examples/tool_put.yml

-v【VERSION】：（选填）工具版本，不填默认为1，后面版本自动加1
下载工具配置文件
```
 gwc tool get -n NAME [-v VERSION] [-o OUTPUT]
```
参数说明：

-n【NAME】：（必填）工具名称

-v【VERSION】：（选填）工具版本，不填默认为最新版本

-o【OUTPUT】：（选填）指定输出文件的路径，不填则输出到屏幕

提示：

可对下载的工具配置文件进行修改，修改后的配置文件用于更新工具配置文件或创建工具（含新版本）。

不支持下载公共工具（public账号）的配置文件。
更新工具配置文件
```
 gwc tool update -n NAME -c CONFIGS [-v VERSION]
```
参数说明：

-n【NAME】：（必填）工具名称

-c【CONFIGS】：（必填）工具配置文件（yaml格式），可通过“下载工具配置文件”（get）获取并对其进行修改

-v【VERSION】：（选填）工具版本，不填默认为最新版本
删除工具
```
 gwc tool delete -n NAME [-v VERSION]
```
参数说明：

-n【NAME】：（必填）工具名称

-v【VERSION】：（选填）工具版本，不填默认为最新版本

(4) 任务相关操作

列出所有任务的状态信息
```
 gwc task ls [-s SIZE] [-f FROMDATE] [-t TODATE]
```
参数说明：

-s【SIZE】：（选填，默认值100）返回的最大条目数。

-f【FROMDATE】：（选填）查询开始时间点，格式为“%Y-%m-%d”，代表“%Y-%m-%d 00:00:00”。不填时，默认值为查询结束时间点的7天前。

-t【TODATE】：（选填）查询结束时间点，格式为“%Y-%m-%d”，代表“%Y-%m-%d 00:00:00”。不填时，默认值为当前时刻。

提示：

不填from和to参数时，默认返回最近7天内提交的任务信息。返回信息中，例如：”Total tasks: 136, Count tasks: 2“ 表示当前用户在GeneDock平台（查询时间范围内，默认最近7天）提交的任务总数是136，目前列出了最近提交的2个任务的信息（指定SIZE为2）。
查看指定任务的状态信息
```
 gwc task get -i TASKID
```
参数说明：

-i【TASKID】：（必填）任务ID
获取指定任务的作业信息
```
gwc task get jobs -i TASKID
```
参数说明：
-i 【TASKID】：（必填）任务ID
-q ：（选填）只输出作业ID
获取指定任务的作业日志
```
gwc task getjobslog -i TASKID
```
参数说明：
-i 【TASKID】：（必填）任务ID
删除任务
```
 gwc task delete -i TASKID
```
参数说明：

-i【TASKID】：（必填）任务ID
停止任务
```
 gwc task stop -i TASKID
```
参数说明：

-i【TASKID】：（必填）任务ID

提示：

只能停止状态为running的任务。
```
 gwc job ls -i TASKID
```
参数说明：

-i【TASKID】：（必填）任务ID

获取指定job的command
```
 gwc job getcmd -j JOBID
```
备注：不适用于wdl工作流

参数说明：

-j【JOBID】：（必填）作业 ID

提示：

通过 “gwc task getjobs” 列举指定task下所有job的信息，可获得某个job的job id。

只能获取对相关工具有编辑权限（即自己账号下创建的工具）的job的command。
获取指定job的日志

```
gwc job getlog -j JOBID
```
备注：不适用于wdl工作流
> **参数说明：**

> -j【JOBID】：（必填）作业 ID

> -o [OUTPUT]： (选填)日志输出文件名称

提示：

日志存放路径
默认的日志存放路径为：

~/.genedock/gwc/logs/

如果您的系统语系(locale)不支持中文，运行当前版本gwc (GeneDock workflow client) 的过程中可能会出现：“error: ‘ascii’ codec can’t encode characters in position xx-xx: ordinal not in range(128)”错误信息。以Linux为例，可通过下述方法来设置语系变量：

安装en_US.UTF-8语言包
```
  sudo locale-gen en_US.UTF-8
```

设置语系变量

临时修改，在关闭Shell时失效：

  sudo export LC_ALL='en_US.utf8'

永久修改，修改配置文件：

  $ sudo vi ~/.bashrc
  添加：export LC_ALL='en_US.utf8'，保存并退出
  $ sudo source ~/.bashrc

查看语系设置

  $ locale
  LANG=
  LANGUAGE=
  LC_CTYPE="en_US.utf8"
  LC_NUMERIC="en_US.utf8"
  LC_TIME="en_US.utf8"
  LC_COLLATE="en_US.utf8"
  LC_MONETARY="en_US.utf8"
  LC_MESSAGES="en_US.utf8"
  LC_PAPER="en_US.utf8"
  LC_NAME="en_US.utf8"
  LC_ADDRESS="en_US.utf8"
  LC_TELEPHONE="en_US.utf8"
  LC_MEASUREMENT="en_US.utf8"
  LC_IDENTIFICATION="en_US.utf8"
  LC_ALL=en_US.utf8

上面的输出表明您已成功修改语系变量。